SGI Freeware 1999 August/SGI Freeware 1999 August.iso/dist/fw_perl.idb/usr/freeware/catman/p_man/cat3/DynaLoader.Z/DynaLoader

Text File | 1998-10-28 | 17.7 KB | 529 lines

     DDDDyyyynnnnaaaaLLLLooooaaaaddddeeeerrrr((((3333))))   22223333////OOOOcccctttt////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))     DDDDyyyynnnnaaaaLLLLooooaaaaddddeeeerrrr((((3333))))



     NNNNAAAAMMMMEEEE
      DynaLoader - Dynamically load    C libraries into Perl code

      _d_l__e_r_r_o_r(), _d_l__f_i_n_d_f_i_l_e(), _d_l__e_x_p_a_n_d_s_p_e_c(), _d_l__l_o_a_d__f_i_l_e(),
      _d_l__f_i_n_d__s_y_m_b_o_l(), _d_l__f_i_n_d__s_y_m_b_o_l__a_n_y_w_h_e_r_e(),
      _d_l__u_n_d_e_f__s_y_m_b_o_l_s(), _d_l__i_n_s_t_a_l_l__x_s_u_b(), _d_l__l_o_a_d__f_l_a_g_s(),
      _b_o_o_t_s_t_r_a_p() -    routines used by DynaLoader modules

     SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
          package YourPackage;
          require DynaLoader;
          @ISA = qw(... DynaLoader ...);
          bootstrap    YourPackage;

          #    optional method    for 'global' loading
          sub dl_load_flags    { 0x01 }


     DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
      This document    defines    a standard generic interface to    the
      dynamic linking mechanisms available on many platforms.  Its
      primary purpose is to    implement automatic dynamic loading of
      Perl modules.

      This document    serves as both a specification for anyone
      wishing to implement the DynaLoader for a new    platform and
      as a guide for anyone    wishing    to use the DynaLoader directly
      in an    application.

      The DynaLoader is designed to    be a very simple high-level
      interface that is sufficiently general to cover the
      requirements of SunOS, HP-UX,    NeXT, Linux, VMS and other
      platforms.

      It is    also hoped that    the interface will cover the needs of
      OS/2,    NT etc and also    allow pseudo-dynamic linking (using ld
      -A at    runtime).

      It must be stressed that the DynaLoader, by itself, is
      practically useless for accessing non-Perl libraries because
      it provides almost no    Perl-to-C 'glue'.  There is, for
      example, no mechanism    for calling a C    library    function or
      supplying arguments.    A C::DynaLib module is available from
      CPAN sites which performs that function for some common
      system types.

      DynaLoader Interface Summary








     Page 1                        (printed 10/23/98)






     DDDDyyyynnnnaaaaLLLLooooaaaaddddeeeerrrr((((3333))))   22223333////OOOOcccctttt////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))     DDDDyyyynnnnaaaaLLLLooooaaaaddddeeeerrrr((((3333))))



        @dl_library_path
        @dl_resolve_using
        @dl_require_symbols
        $dl_debug
        @dl_librefs
        @dl_modules
                                Implemented    in:
        bootstrap($modulename)                 Perl
        @filepaths = dl_findfile(@names)             Perl
        $flags = $modulename->dl_load_flags             Perl
        $symref  = dl_find_symbol_anywhere($symbol)         Perl

        $libref  = dl_load_file($filename, $flags)         C
        $symref  = dl_find_symbol($libref, $symbol)         C
        @symbols = dl_undef_symbols()             C
        dl_install_xsub($name, $symref [, $filename])     C
        $message = dl_error                     C


      @dl_library_path
          The standard/default list    of directories in which
          _d_l__f_i_n_d_f_i_l_e() will search    for libraries etc.
          Directories are searched in order:  $dl_library_path[0],
          [1], ... etc

          @dl_library_path is initialised to hold the list of
          'normal' directories (/_u_s_r/_l_i_b, etc) determined by
          CCCCoooonnnnffffiiiigggguuuurrrreeee    ($Config{'libpth'}).  This should ensure
          portability across a wide    range of platforms.

          @dl_library_path should also be initialised with any
          other directories    that can be determined from the
          environment at runtime (such as LD_LIBRARY_PATH for
          SunOS).

          After initialisation @dl_library_path can    be manipulated
          by an application    using push and unshift before calling
          _d_l__f_i_n_d_f_i_l_e().  Unshift can be used to add directories
          to the front of the search order either to save search
          time or to override libraries with the same name in the
          'normal' directories.

          The load function    that _d_l__l_o_a_d__f_i_l_e() calls may require
          an absolute pathname.  The _d_l__f_i_n_d_f_i_l_e() function    and
          @dl_library_path can be used to search for and return
          the absolute pathname for    the library/object that    you
          wish to load.

      @dl_resolve_using
          A    list of    additional libraries or    other shared objects
          which can    be used    to resolve any undefined symbols that
          might be generated by a later call to _l_o_a_d__f_i_l_e().



     Page 2                        (printed 10/23/98)






     DDDDyyyynnnnaaaaLLLLooooaaaaddddeeeerrrr((((3333))))   22223333////OOOOcccctttt////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))     DDDDyyyynnnnaaaaLLLLooooaaaaddddeeeerrrr((((3333))))



          This is only required on some platforms which do not
          handle dependent libraries automatically.     For example
          the Socket Perl extension    library
          (_a_u_t_o/_S_o_c_k_e_t/_S_o_c_k_e_t._s_o) contains references to many
          socket functions which need to be    resolved when it's
          loaded.  Most platforms will automatically know where to
          find the 'dependent' library (e.g.,
          /_u_s_r/_l_i_b/_l_i_b_s_o_c_k_e_t._s_o).  A few platforms need to be told
          the location of the dependent library explicitly.     Use
          @dl_resolve_using    for this.

          Example usage:

          @dl_resolve_using = dl_findfile('-lsocket');


      @dl_require_symbols
          A    list of    one or more symbol names that are in the
          library/object file to be    dynamically loaded.  This is
          only required on some platforms.

      @dl_librefs
          An array of the handles returned by successful calls to
          _d_l__l_o_a_d__f_i_l_e(), made by bootstrap, in the    order in which
          they were    loaded.     Can be    used with _d_l__f_i_n_d__s_y_m_b_o_l() to
          look for a symbol    in any of the loaded files.

      @dl_modules
          An array of module (package) names that have been
          bootstrap'ed.

      dl_error()
          Syntax:

          $message = dl_error();

          Error message text from the last failed DynaLoader
          function.     Note that, similar to errno in    unix, a
          successful function call does not    reset this message.

          Implementations should detect the    error as soon as it
          occurs in    any of the other functions and save the
          corresponding message for    later retrieval.  This will
          avoid problems on    some platforms (such as    SunOS) where
          the error    message    is very    temporary (e.g., _d_l_e_r_r_o_r()).

      $dl_debug
          Internal debugging messages are enabled when $dl_debug
          is set true.  Currently setting $dl_debug    only affects
          the Perl side of the DynaLoader.    These messages should
          help an application developer to resolve any DynaLoader
          usage problems.



     Page 3                        (printed 10/23/98)






     DDDDyyyynnnnaaaaLLLLooooaaaaddddeeeerrrr((((3333))))   22223333////OOOOcccctttt////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))     DDDDyyyynnnnaaaaLLLLooooaaaaddddeeeerrrr((((3333))))



          $dl_debug    is set to $ENV{'PERL_DL_DEBUG'}    if defined.

          For the DynaLoader developer/porter there    is a similar
          debugging    variable added to the C    code (see dlutils.c)
          and enabled if Perl was built with the ----DDDDDDDDEEEEBBBBUUUUGGGGGGGGIIIINNNNGGGG flag.
          This can also be set via the PERL_DL_DEBUG environment
          variable.     Set to    1 for minimal information or higher
          for more.

      dl_findfile()
          Syntax:

          @filepaths = dl_findfile(@names)

          Determine    the full paths (including file suffix) of one
          or more loadable files given their generic names and
          optionally one or    more directories.  Searches
          directories in @dl_library_path by default and returns
          an empty list if no files    were found.

          Names can    be specified in    a variety of platform
          independent forms.  Any names in the form    ----llllnnnnaaaammmmeeee are
          converted    into _l_i_b_n_a_m_e.*,    where .* is an appropriate
          suffix for the platform.

          If a name    does not already have a    suitable prefix    and/or
          suffix then the corresponding file will be searched for
          by trying    combinations of    prefix and suffix appropriate
          to the platform: "$name.o", "lib$name.*"    and "$name".

          If any directories are included in @names    they are
          searched before @dl_library_path.     Directories may be
          specified    as ----LLLLddddiiiirrrr.  Any other names are treated as
          filenames    to be searched for.

          Using arguments of the form -Ldir    and -lname is
          recommended.

          Example:

          @dl_resolve_using = dl_findfile(qw(-L/usr/5lib -lposix));


      dl_expandspec()
          Syntax:

          $filepath = dl_expandspec($spec)

          Some unusual systems, such as VMS, require special
          filename handling    in order to deal with symbolic names
          for files    (i.e., VMS's Logical Names).




     Page 4                        (printed 10/23/98)






     DDDDyyyynnnnaaaaLLLLooooaaaaddddeeeerrrr((((3333))))   22223333////OOOOcccctttt////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))     DDDDyyyynnnnaaaaLLLLooooaaaaddddeeeerrrr((((3333))))



          To support these systems a _d_l__e_x_p_a_n_d_s_p_e_c() function can
          be implemented either in the _d_l_*._x_s file    or code    can be
          added to the autoloadable    _d_l__e_x_p_a_n_d_s_p_e_c()    function in
          _D_y_n_a_L_o_a_d_e_r._p_m.  See _D_y_n_a_L_o_a_d_e_r._p_m    for more information.

      dl_load_file()
          Syntax:

          $libref = dl_load_file($filename, $flags)

          Dynamically load $filename, which    must be    the path to a
          shared object or library.     An opaque 'library reference'
          is returned as a handle for the loaded object.  Returns
          undef on error.

          The $flags argument to alters dl_load_file behaviour.
          Assigned bits:

           0x01  make symbols available for    linking    later dl_load_file's.
             (only known to work on Solaris 2 using dlopen(RTLD_GLOBAL))
             (ignored under VMS; this is a normal part of image    linking)

          (On systems that provide a handle    for the    loaded object
          such as SunOS and    HPUX, $libref will be that handle.  On
          other systems $libref will typically be $filename    or a
          pointer to a buffer containing $filename.     The
          application should not examine or    alter $libref in any
          way.)

          This is the function that    does the real work.  It    should
          use the current values of    @dl_require_symbols and
          @dl_resolve_using    if required.

          SunOS: dlopen($filename)
          HP-UX: shl_load($filename)
          Linux: dld_create_reference(@dl_require_symbols); dld_link($filename)
          NeXT:     rld_load($filename, @dl_resolve_using)
          VMS:     lib$find_image_symbol($filename,$dl_require_symbols[0])

          (The _d_l_o_p_e_n() function is    also used by Solaris and some
          versions of Linux, and is    a common choice    when providing
          a    "wrapper" on other mechanisms as is done in the    OS/2
          port.)

      dl_loadflags()
          Syntax:

          $flags = dl_loadflags    $modulename;

          Designed to be a method call, and    to be overridden by a
          derived class (i.e. a class which    has DynaLoader in its
          @ISA).  The definition in    DynaLoader itself returns 0,



     Page 5                        (printed 10/23/98)






     DDDDyyyynnnnaaaaLLLLooooaaaaddddeeeerrrr((((3333))))   22223333////OOOOcccctttt////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))     DDDDyyyynnnnaaaaLLLLooooaaaaddddeeeerrrr((((3333))))



          which produces standard behavior from _d_l__l_o_a_d__f_i_l_e().

      dl_find_symbol()
          Syntax:

          $symref = dl_find_symbol($libref, $symbol)

          Return the address of the    symbol $symbol or undef    if not
          found.  If the target system has separate    functions to
          search for symbols of different types then
          _d_l__f_i_n_d__s_y_m_b_o_l() should search for function symbols
          first and    then other types.

          The exact    manner in which    the address is returned    in
          $symref is not currently defined.     The only initial
          requirement is that $symref can be passed    to, and
          understood by, _d_l__i_n_s_t_a_l_l__x_s_u_b().

          SunOS: dlsym($libref,    $symbol)
          HP-UX: shl_findsym($libref, $symbol)
          Linux: dld_get_func($symbol) and/or dld_get_symbol($symbol)
          NeXT:     rld_lookup("_$symbol")
          VMS:     lib$find_image_symbol($libref,$symbol)


      dl_find_symbol_anywhere()
          Syntax:

          $symref = dl_find_symbol_anywhere($symbol)

          Applies _d_l__f_i_n_d__s_y_m_b_o_l() to the members of @dl_librefs
          and returns the first match found.

      dl_undef_symbols()
          Example

          @symbols = dl_undef_symbols()

          Return a list of symbol names which remain undefined
          after _l_o_a_d__f_i_l_e().  Returns () if    not known.  Don't
          worry if your platform does not provide a    mechanism for
          this.  Most do not need it and hence do not provide it,
          they just    return an empty    list.

      dl_install_xsub()
          Syntax:

          dl_install_xsub($perl_name, $symref [, $filename])

          Create a new Perl    external subroutine named $perl_name
          using $symref as a pointer to the    function which
          implements the routine.  This is simply a    direct call to



     Page 6                        (printed 10/23/98)






     DDDDyyyynnnnaaaaLLLLooooaaaaddddeeeerrrr((((3333))))   22223333////OOOOcccctttt////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))     DDDDyyyynnnnaaaaLLLLooooaaaaddddeeeerrrr((((3333))))



          _n_e_w_X_S_U_B().  Returns a reference to the installed
          function.

          The $filename parameter is used by Perl to identify the
          source file for the function if required by _d_i_e(),
          _c_a_l_l_e_r() or the debugger.     If $filename is not defined
          then "DynaLoader"    will be    used.

      bootstrap()
          Syntax:

          _b_o_o_t_s_t_r_a_p($module)

          This is the normal entry point for automatic dynamic
          loading in Perl.

          It performs the following    actions:

      +o          locates an auto/$module directory    by searching
              @INC

      +o          uses _d_l__f_i_n_d_f_i_l_e() to determine the filename to
              load

      +o          sets @dl_require_symbols to ("boot_$module")

      +o          executes an _a_u_t_o/$_m_o_d_u_l_e/$_m_o_d_u_l_e._b_s file if it
              exists (typically    used to    add to
              @dl_resolve_using    any files which    are required
              to load the module on the    current    platform)

      +o          calls _d_l__l_o_a_d__f_l_a_g_s() to determine how to    load
              the file.

      +o          calls _d_l__l_o_a_d__f_i_l_e() to load the file

      +o          calls _d_l__u_n_d_e_f__s_y_m_b_o_l_s() and warns if any
              symbols are undefined

      +o          calls _d_l__f_i_n_d__s_y_m_b_o_l() for "boot_$module"

      +o          calls _d_l__i_n_s_t_a_l_l__x_s_u_b() to install it as
              "${module}::bootstrap"

      +o          calls &{"${module}::bootstrap"} to bootstrap the
              module (actually it uses the function reference
              returned by dl_install_xsub for speed)

     AAAAUUUUTTTTHHHHOOOORRRR
      Tim Bunce, 11    August 1994.

      This interface is based on the work and comments of (in no



     Page 7                        (printed 10/23/98)






     DDDDyyyynnnnaaaaLLLLooooaaaaddddeeeerrrr((((3333))))   22223333////OOOOcccctttt////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))     DDDDyyyynnnnaaaaLLLLooooaaaaddddeeeerrrr((((3333))))



      particular order): Larry Wall, Robert    Sanders, Dean
      Roehrich, Jeff Okamoto, Anno Siegel, Thomas Neumann, Paul
      Marquess, Charles Bailey, myself and others.

      Larry    Wall designed the elegant inherited bootstrap
      mechanism and    implemented the    first Perl 5 dynamic loader
      using    it.

      Solaris global loading added by Nick Ing-Simmons with
      design/coding    assistance from    Tim Bunce, January 1996.













































     Page 8                        (printed 10/23/98)